home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / other / guigfxlib / doc / autodoc / guigfx.doc < prev    next >
Text File  |  1999-06-14  |  78KB  |  2,090 lines
  1. TABLE OF CONTENTS
  2.  
  3. guigfx.library/AddPaletteA
  4. guigfx.library/AddPictureA
  5. guigfx.library/AddPixelArrayA
  6. guigfx.library/ClonePictureA
  7. guigfx.library/CreateDirectDrawHandleA
  8. guigfx.library/CreatePenShareMapA
  9. guigfx.library/CreatePictureBitMapA
  10. guigfx.library/CreatePictureMaskA
  11. guigfx.library/DeleteDirectDrawHandle
  12. guigfx.library/DeletePenShareMap
  13. guigfx.library/DeletePicture
  14. guigfx.library/DirectDrawTrueColorA
  15. guigfx.library/DoPictureMethodA
  16. guigfx.library/DrawPictureA
  17. guigfx.library/GetPictureAttrsA
  18. guigfx.library/IsPictureA
  19. guigfx.library/LoadPictureA
  20. guigfx.library/LockPictureA
  21. guigfx.library/MakePictureA
  22. guigfx.library/ObtainDrawHandleA
  23. guigfx.library/ReadPictureA
  24. guigfx.library/ReleaseDrawHandle
  25. guigfx.library/RemColorHandle
  26. guigfx.library/UnLockPicture
  27. guigfx.library/AddPaletteA                         guigfx.library/AddPaletteA
  28.  
  29.     NAME
  30.         AddPaletteA - add a palette's colors to a pen-sharemap.
  31.         AddPalette  - varargs stub for AddPaletteA.
  32.  
  33.     SYNOPSIS
  34.         colorhandle = AddPaletteA(psm,palette,taglist)
  35.         d0                        a0  a1      a2
  36.  
  37.         APTR AddPaletteA(APTR,APTR,struct TagItem *)
  38.         
  39.         APTR AddPalette(APTR,APTR,tag,...,TAG_DONE)
  40.  
  41.     FUNCTION
  42.         This function adds a palette's colors to a pen-sharemap.
  43.  
  44.     INPUTS
  45.         psm         - pointer to a pen-sharemap
  46.         palette     - pointer to a color table
  47.         tags        - pointer to an array of TagItems
  48.  
  49.     TAGS
  50.         GGFX_PaletteFormat (ULONG) - format of the palette. Currently
  51.                 defined are:
  52.                       
  53.                 PALFMT_RGB8
  54.                         ULONG 0x00rrggbb
  55.  
  56.                 PALFMT_RGB32
  57.                         ULONG red,green,blue. This is the LoadRGB32()
  58.                         format without trailing longword.
  59.  
  60.                 Default: PALFMT_RGB8
  61.                 
  62.         GGFX_NumColors (ULONG) - number of colors in the color table.
  63.                 Currently, this argument is mandatory. Default: 0
  64.         
  65.         GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
  66.                 With this factor, you can specify a significance
  67.                 for this color instance. The higher this value, the
  68.                 higher the palette's influence on the pen-sharemap.
  69.                 Default: 1
  70.  
  71.     RESULTS
  72.         colorhandle - identifier for a particular dependency between
  73.                       color information and pen-sharemap. there is
  74.                       no need for you to store a colorhandle, unless
  75.                       you want to manually remove it from the pen-sharemap
  76.                       via RemColorHandle(). NULL if something went wrong.
  77.  
  78.     NOTES
  79.         An example is provided with the documentation for AddPictureA().
  80.  
  81.     SEE ALSO
  82.         RemColorHandle(), AddPictureA(), AddPixelArrayA(),
  83.         CreatePenShareMapA(), DeletePenShareMap(), ObtainDrawHandleA()
  84.  
  85.  
  86. guigfx.library/AddPictureA                         guigfx.library/AddPictureA
  87.  
  88.     NAME
  89.         AddPictureA - add a picture's color information to a pen-sharemap.
  90.         AddPicture  - varargs stub for AddPictureA.
  91.  
  92.     SYNOPSIS
  93.         colorhandle = AddPictureA(psm,picture,taglist)
  94.         d0                        a0  a1      a2
  95.  
  96.         APTR AddPictureA(APTR,APTR,struct TagItem *)
  97.         
  98.         APTR AddPicture(APTR,APTR,tag,...,TAG_DONE)
  99.  
  100.     FUNCTION
  101.         This function adds a picture's color information to
  102.         a pen-sharemap.
  103.  
  104.     INPUTS
  105.         psm         - pointer to a pen-sharemap
  106.         picture     - pointer to a picture
  107.         tags        - pointer to an array of TagItems
  108.  
  109.     TAGS
  110.         GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
  111.                 With this factor, you can specify a significance
  112.                 for this color instance. The higher this value, the
  113.                 higher the picture's influence on the pen-sharemap.
  114.                 Default: 1
  115.         
  116.     RESULTS
  117.         colorhandle - identifier for a particular dependency between
  118.                       color information and pen-sharemap. there is
  119.                       no need for you to store a colorhandle, unless
  120.                       you want to manually remove it from the pen-sharemap
  121.                       via RemColorHandle(). NULL if something went wrong.
  122.  
  123.     EXAMPLE
  124.         Assume there were three different pictures to be drawn.
  125.  
  126.         a) a noisy background
  127.         b) a logo of your company
  128.         c) navigation icons
  129.  
  130.         you might want to differenciate the significances for these 
  131.         pictures as follows:
  132.  
  133.         AddPicture(psm, backpic, GGFX_Weight, 2, TAG_DONE);
  134.         AddPicture(psm, logopic, GGFX_Weight, 3, TAG_DONE);
  135.         AddPicture(psm, navpic, GGFX_Weight, 5, TAG_DONE);
  136.  
  137.         the backpic's influence on the allocated pens would be 20%, the logo
  138.         contributed with 30%, and the navigation buttons would be taken into
  139.         account with 50% then.
  140.  
  141.     NOTES
  142.         
  143.     SEE ALSO
  144.         RemColorHandle(), AddPaletteA(), AddPixelArrayA(),
  145.         CreatePenShareMapA(), DeletePenShareMap(), ObtainDrawHandleA()
  146.  
  147.  
  148. guigfx.library/AddPixelArrayA                   guigfx.library/AddPixelArrayA
  149.  
  150.     NAME
  151.         AddPixelArrayA - add a pixel array's color information to a
  152.                          pen-sharemap.
  153.         AddPixelArray  - varargs stub for AddPixelArrayA.
  154.  
  155.     SYNOPSIS
  156.         colorhandle = AddPixelArrayA(psm,array,width,height,taglist)
  157.         d0                           a0  a1    d0    d1     a2
  158.  
  159.         APTR AddPixelArrayA(APTR,APTR,UWORD,UWORD,struct TagItem *)
  160.         
  161.         APTR AddPixelArray(APTR,APTR,UWORD,UWORD,tag,...,TAG_DONE)
  162.  
  163.     FUNCTION
  164.         This function adds a pixel array's color information to a
  165.         pen-sharemap.
  166.  
  167.     INPUTS
  168.         psm         - pointer to a pen-sharemap
  169.         pixelarray  - pointer to a pixel array
  170.         width       - pixel array's width [pixels]
  171.         height      - pixel array's height [rows]
  172.         tags        - pointer to an array of TagItems
  173.  
  174.     TAGS
  175.         GGFX_PixelFormat (ULONG) - pixel format. Currently defined are
  176.  
  177.                 PIXFMT_CHUNKY_CLUT
  178.                         chunky bytes, directly acting as indices
  179.                         to a color-lookup-table. You must specify the
  180.                         GGFX_Palette and GGFX_NumColors tags as well.
  181.                 
  182.                 PIXFMT_0RGB_32
  183.                         truecolor pixels (ULONG 0x00rrggbb).
  184.  
  185.                 Default: PIXFMT_CHUNKY_CLUT               
  186.  
  187.         GGFX_Palette (APTR) - pointer to a color table. Mandatory for
  188.                 PIXFMT_CHUNKY_CLUT (see above).
  189.                 Default: none
  190.  
  191.         GGFX_NumColors (ULONG) - number of colors in the color table.
  192.                 Mandatory for PIXFMT_CHUNKY_CLUT (see above).
  193.                 Default: none
  194.  
  195.         GGFX_PaletteFormat (ULONG) - format of the palette. Currently
  196.                 defined are:
  197.                       
  198.                 PALFMT_RGB8
  199.                         ULONG 0x00rrggbb
  200.  
  201.                 PALFMT_RGB32
  202.                         ULONG red,green,blue. This is the LoadRGB32()
  203.                         format without trailing longword.
  204.  
  205.                 Default: PALFMT_RGB8
  206.  
  207.         GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
  208.                 With this factor, you can specify a significance
  209.                 for this color instance. The higher this value, the
  210.                 higher the pixel array's influence on the pen-sharemap.
  211.                 Default: 1
  212.         
  213.     RESULTS
  214.         colorhandle - identifier for a particular dependency between
  215.                       color information and pen-sharemap. there is
  216.                       no need for you to store a colorhandle, unless
  217.                       you want to manually remove it from the pen-sharemap
  218.                       via RemColorHandle(). NULL if something went wrong.
  219.  
  220.     NOTES
  221.         An example is provided with the documentation for AddPictureA().
  222.  
  223.     SEE ALSO
  224.         RemColorHandle(), AddPaletteA(), AddPictureA(),
  225.         CreatePenShareMapA(), DeletePenShareMap(), ObtainDrawHandleA()
  226.  
  227.  
  228. guigfx.library/ClonePictureA                     guigfx.library/ClonePictureA
  229.  
  230.     NAME
  231.         ClonePictureA - create a duplicate from a picture.
  232.         ClonePicture  - varargs stub for ClonePictureA.
  233.  
  234.     SYNOPSIS
  235.         newpicture = ClonePictureA(picture,taglist)
  236.         d0                         a0      a1
  237.  
  238.         APTR ClonePictureA(APTR,struct TagItem *)
  239.         
  240.         APTR ClonePicture(APTR,tag,...,TAG_DONE)
  241.  
  242.     FUNCTION
  243.         This function creates a duplicate from a picture. Memory will
  244.         be allocated, and the picture will be copied including all its
  245.         attributes. Optionally, the picture is cloned only in part.
  246.  
  247.     INPUTS
  248.         picture     - pointer to a picture
  249.         tags        - pointer to an array of TagItems
  250.  
  251.     TAGS
  252.         GGFX_SourceX (ULONG)
  253.                 left edge inside the picture where to fetch the pixels
  254.                 from [pixels]. Default: 0.
  255.  
  256.         GGFX_SourceY (ULONG)
  257.                 top edge inside the picture where to fetch the pixels
  258.                 from [rows]. Default: 0.
  259.  
  260.         GGFX_SourceWidth (ULONG)
  261.                 width of an area inside the picture [pixels].
  262.                 Default: The picture's width.
  263.  
  264.         GGFX_SourceHeight (ULONG)
  265.                 height of an area inside the picture [rows].
  266.                 Default: The picture's height.
  267.  
  268.         GGFX_DestWidth (ULONG)
  269.                 width of the new picture [pixels].
  270.                 Default: The picture's width.
  271.  
  272.         GGFX_DestHeight (ULONG)
  273.                 height of the new picture [rows].
  274.                 Default: The picture's height.
  275.  
  276.     RESULTS
  277.         newpicture  - a vanilla copy of the specified picture (or a
  278.                       part of it), or NULL if there was not enough memory
  279.                       available.
  280.  
  281.     SEE ALSO
  282.         MakePictureA(), DeletePicture()
  283.  
  284.  
  285. guigfx.library/CreateDirectDrawHandleA guigfx.library/CreateDirectDrawHandleA
  286.  
  287.     NAME
  288.         CreateDirectDrawHandleA - derive a handle for 'direct' drawing (v9)
  289.         CreateDirectDrawHandle  - varargs stub for CreateDirectDrawHandleA
  290.     
  291.     SYNOPSIS
  292.         ddh = CreateDirectDrawHandleA(drawhandle,sourcewidth,sourceheight,
  293.                                       a0        d0          d1
  294.                                       destwidth,destheight,taglist) 
  295.                                       d2        d3         a1
  296.  
  297.         APTR CreateDirectDrawHandleA(APTR,UWORD,UWORD,UWORD,UWORD,
  298.                                      struct TagItem *)
  299.  
  300.         APTR CreateDirectDrawHandle(APTR,UWORD,UWORD,UWORD,UWORD,
  301.                                     Tag,...,TAG_DONE)
  302.  
  303.     FUNCTION
  304.         Derive a handle from a drawhandle for highly optimized
  305.         ('direct') drawing function calls. Currently only truecolor
  306.         data (PIXFMT_0RGB_32) are supported.
  307.  
  308.     INPUTS
  309.         drawhandle   - drawhandle from which to derive a directdrawhandle
  310.         sourcewidth  - source width [pixels]
  311.         sourceheight - source height [rows]
  312.         destwidth    - dest width [pixels]
  313.         destheight   - dest height [rows]
  314.         tags         - pointer to an array of TagItems
  315.  
  316.     TAGS
  317.         GGFX_PixelFormat - type of pixels to be processed. Currently
  318.              only PIXFMT_0RGB_32 is supported.
  319.              Default: PIXFMT_0RGB_32
  320.  
  321.     RESULTS
  322.          ddh   - a direct-drawhandle, an object that can be passed
  323.                  to DirectDrawTrueColorA()
  324.  
  325.     NOTES
  326.          You must free the direct-drawhandle with a matching call
  327.          to DeleteDirectDrawHandle(). You are not allowed to free
  328.          the underlying drawhandle before the direct-drawhandle.
  329.          The consequences might be fatal.
  330.  
  331.     SEE ALSO
  332.         DeleteDirectDrawHandle(), DirectDrawTrueColorA(),
  333.         ObtainDrawHandleA()
  334.  
  335.  
  336. guigfx.library/CreatePenShareMapA           guigfx.library/CreatePenShareMapA
  337.  
  338.     NAME
  339.         CreatePenShareMapA - create a screen-pen manager.
  340.         CreatePenShareMap  - varargs stub for CreatePenShareMapA.
  341.  
  342.     SYNOPSIS
  343.         psm = CreatePenShareMapA(taglist)
  344.         d0                       a0
  345.  
  346.         APTR CreatePenShareMapA(struct TagItem *)
  347.         
  348.         APTR CreatePenShareMap(tag,...,TAG_DONE)
  349.  
  350.     FUNCTION
  351.         This function creates a screen-pen manager.
  352.  
  353.     INPUTS
  354.         tags        - pointer to an array of TagItems
  355.  
  356.     TAGS
  357.         GGFX_HSType (ULONG) - internal histogram type, according to
  358.                 the histogram types defined in render/render.h.
  359.                 Better you never touch this tag, unless you know exactly
  360.                 what you are doing. Also consider reading the 'memory' text
  361.                 file supplied with the render.library distribution.
  362.                 Default: HSTYPE_12BIT_TURBO
  363.         
  364.     RESULTS
  365.         psm   - a pen-sharemap ready for usage or NULL if there was not
  366.                 enough memory available.
  367.  
  368.     NOTES
  369.         The term 'pen-sharemap' might be confusing and has been
  370.         maintained for consistency reasons. It is actually a
  371.         histogram that collects color statistics. When a
  372.         pen-sharemap is passed to ObtainDrawHandleA(), it allows
  373.         to calculate a very specific palette.
  374.         
  375.     SEE ALSO
  376.         DeletePenShareMap(), ObtainDrawHandleA(), AddPictureA(),
  377.         AddPaletteA(), AddPixelArrayA()
  378.  
  379.  
  380. guigfx.library/CreatePictureBitMapA       guigfx.library/CreatePictureBitMapA
  381.  
  382.     NAME
  383.         CreatePictureBitMapA - create a BitMap from a picture.
  384.         CreatePictureBitMap  - varargs stub for CreatePictureBitMapA.
  385.  
  386.     SYNOPSIS
  387.         bitmap = CreatePictureBitMapA(drawhandle,picture,tags)
  388.         d0                            a0         a1      a2
  389.  
  390.         struct BitMap *CreatePictureBitMapA(APTR,APTR,struct TagItem *)
  391.  
  392.         struct BitMap *CreatePictureBitMap(APTR,APTR,tag,...,TAG_DONE)
  393.  
  394.     FUNCTION
  395.         This function creates a BitMap from a drawhandle and from
  396.         a picture. This BitMap will be applicable to the drawhandle's
  397.         RastPort and ColorMap, i.e. it may use colors allocated with
  398.         the drawhandle, and can be blitted efficiently to the RastPort
  399.         with graphics.library functions.
  400.         
  401.         If the picture argument is ommitted (i.e. NULL), then this
  402.         function creates a blank, displayable BitMap that can be
  403.         blitted efficiently to the drawhandle's RastPort. Note: The
  404.         tags GGFX_DestWidth and GGFX_DestHeight are mandatory if no
  405.         picture is specified, and all other tags will be ignored. (v15)
  406.         
  407.         Note: The BitMap structure must be freed with
  408.         graphics.library/FreeBitMap().
  409.  
  410.     INPUTS
  411.         drawhandle  - pointer to a drawhandle from ObtainDrawHandleA()
  412.         picture     - pointer to a picture, or NULL.
  413.         tags        - pointer to an array of TagItems
  414.  
  415.     TAGS
  416.         GGFX_DestWidth (ULONG)
  417.                 destination width for the BitMap [pixels].
  418.                 Mandatory if no picture is supplied.
  419.                 Default: the picture's width.
  420.  
  421.         GGFX_DestHeight (ULONG)
  422.                 destination height for the BitMap [rows].
  423.                 Mandatory if no picture is supplied.
  424.                 Default: the picture's height.
  425.  
  426.         GGFX_SourceX (ULONG)
  427.                 left edge inside the picture where to fetch the pixels
  428.                 from [pixels]. Default: 0.
  429.  
  430.         GGFX_SourceY (ULONG)
  431.                 top edge inside the picture where to fetch the pixels
  432.                 from [rows]. Default: 0.
  433.  
  434.         GGFX_SourceWidth (ULONG)
  435.                 width of an area inside the picture [pixels].
  436.                 Default: The picture's width.
  437.  
  438.         GGFX_SourceHeight (ULONG)
  439.                 height of an area inside the picture [rows].
  440.                 Default: The picture's height.
  441.  
  442.         GGFX_CallBackHook (struct Hook *)
  443.                 pointer to a callback Hook structure. The associated
  444.                 callback function will be called from time to time
  445.                 while the picture is being rendered to the BitMap.
  446.                 The callback has to return TRUE for continuation or FALSE
  447.                 for abortion. It will be submitted a pointer to the
  448.                 picture for the object, and a message of the following
  449.                 type:
  450.  
  451.                         ULONG GGFX_MSGTYPE_LINEDRAWN
  452.                         ULONG line_number
  453.                 
  454.                 Also refer to the example provided with DrawPictureA().
  455.                 Default: NULL.
  456.  
  457.         GGFX_DitherMode (ULONG) - dither mode. Currently available are:
  458.  
  459.                 DITHERMODE_NONE
  460.                         no dithering at all
  461.                 
  462.                 DITHERMODE_FS
  463.                         Floyd-Steinberg dithering
  464.                         
  465.                 DITHERMODE_RANDOM
  466.                         Random dithering. This mode is significantly
  467.                         slower than Floyd-Steinberg dithering.
  468.  
  469.                 DITHERMODE_EDD
  470.                         EDD dithering. This mode is faster than
  471.                         Floyd-Steinberg dithering.
  472.  
  473.                 Default: The drawhandle's dithermode.
  474.  
  475.         GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
  476.                 Currently, this value is of any use only for
  477.                 DITHERMODE_RANDOM. Default: The drawhandle's dither amount.
  478.  
  479.     RESULTS
  480.         bitmap     - a BitMap structure ready for being blitted to
  481.                      the RastPort via graphics.library/BltBitMapRastPort(),
  482.                      or NULL if there was not enough memory available.
  483.  
  484.     SEE ALSO
  485.         ObtainDrawHandleA(), DrawPictureA(), graphics.library/FreeBitMap(),
  486.         graphics.library/BltBitMapRastPort(), CreatePictureMaskA()
  487.  
  488.  
  489. guigfx.library/CreatePictureMaskA           guigfx.library/CreatePictureMaskA
  490.  
  491.     NAME
  492.         CreatePictureMaskA - create a mask from a picture. (v15)
  493.         CreatePictureMask  - varargs stub for CreatePictureMaskA.
  494.  
  495.     SYNOPSIS
  496.         success = CreatePictureMaskA(picture,array,bytewidth,tags)
  497.         d0                           a0      a1    d0        a2
  498.  
  499.         BOOL CreatePictureMaskA(APTR,UBYTE *,UWORD,struct TagItem *)
  500.  
  501.         BOOL CreatePictureMask(APTR,UBYTE *,UWORD,tag,...,TAG_DONE)
  502.  
  503.     FUNCTION
  504.         This function creates a single-bitplane mask from a picture's
  505.         alpha-channel. This mask can be passed to e.g.
  506.         graphics.library/BltMaskBitMapRastPort() for masked blitting.
  507.         
  508.         If the picture contains no alpha-channel, the resulting
  509.         mask will be completely opaque, i.e. all bits will be set.
  510.         
  511.         Use GGFX_Ratio to specify a threshold. Alpha-channel values
  512.         below this threshold will be rendered to a clear bit, values
  513.         greater or equal to a set bit.
  514.         
  515.         The array argument must point to a single bitplane, with an
  516.         alignment according to ((width+15)>>4)<<1. The bytewidth must
  517.         be an even number.
  518.         
  519.         Optionally, the alpha-channel is scaled to the resulting
  520.         bitplane.
  521.  
  522.     INPUTS
  523.         picture     - pointer to a picture
  524.         array       - pointer to a single bitplane. reserve at least
  525.                       (((width+15)>>4)<<1)*height bytes.
  526.         bytewidth   - total width of the bitplane array [bytes]
  527.         tags        - pointer to an array of TagItems
  528.  
  529.     TAGS
  530.         GGFX_DestWidth (ULONG)
  531.                 destination width to be used in the resulting
  532.                 bitplane [pixels]. Default: the picture's width.
  533.  
  534.         GGFX_DestHeight (ULONG)
  535.                 destination height to be used in the resulting
  536.                 bitplane [rows]. Default: the picture's height.
  537.  
  538.         GGFX_SourceX (ULONG)
  539.                 left edge inside the picture where to fetch the
  540.                 alpha-channel from [pixels]. Default: 0.
  541.  
  542.         GGFX_SourceY (ULONG)
  543.                 top edge inside the picture where to fetch the
  544.                 alpha-channel from [rows]. Default: 0.
  545.  
  546.         GGFX_SourceWidth (ULONG)
  547.                 width of an area inside the picture [pixels].
  548.                 Default: The picture's width.
  549.  
  550.         GGFX_SourceHeight (ULONG)
  551.                 height of an area inside the picture [rows].
  552.                 Default: The picture's height.
  553.  
  554.         GGFX_Ratio (ULONG) - threshold. Alpha-channel values
  555.                 greater or equal this threshold will appear as
  556.                 a set bit. Default: 128
  557.  
  558.     RESULTS
  559.         success    - boolean, FALSE if there was not enough
  560.                      memory for intermediate buffers
  561.  
  562.     SEE ALSO
  563.         CreatePictureBitMapA(), graphics.library/BltMaskBitMapRastPort()
  564.  
  565.  
  566. guigfx.library/DeleteDirectDrawHandle   guigfx.library/DeleteDirectDrawHandle
  567.  
  568.     NAME
  569.         DeleteDirectDrawHandle - remove a direct-drawhandle. (v9)
  570.     
  571.     SYNOPSIS
  572.         DeleteDirectDrawHandle(ddh)
  573.                                a0
  574.  
  575.         void DeleteDirectDrawHandle(APTR)
  576.  
  577.     FUNCTION
  578.         this function deletes a direct-drawhandle object and frees
  579.         all associated memory.
  580.  
  581.     INPUTS
  582.         ddh - a direct-drawhandle, created with CreateDirectDrawHandleA()
  583.  
  584.     RESULTS
  585.         none
  586.  
  587.     SEE ALSO
  588.         CreateDirectDrawHandleA()
  589.  
  590.  
  591. guigfx.library/DeletePenShareMap             guigfx.library/DeletePenShareMap
  592.  
  593.     NAME
  594.         DeletePenShareMap - dispose a pen-sharemap.
  595.  
  596.     SYNOPSIS
  597.         DeletePenShareMap(psm)
  598.                           a0
  599.  
  600.         void DeletePenShareMap(APTR)
  601.  
  602.     FUNCTION
  603.         This function discards a pen-sharemap and frees all associated
  604.         memory and colorhandles.
  605.  
  606.     INPUTS
  607.         psm      - pointer to a pen-sharemap to be deleted.
  608.         
  609.     SEE ALSO
  610.         CreatePenShareMapA(), RemColorHandle()
  611.  
  612.  
  613. guigfx.library/DeletePicture                     guigfx.library/DeletePicture
  614.  
  615.     NAME
  616.         DeletePicture - dispose a picture.
  617.  
  618.     SYNOPSIS
  619.         DeletePicture(picture)
  620.                       a0
  621.  
  622.         void DeletePicture(APTR)
  623.  
  624.     FUNCTION
  625.         This function discards a picture and frees all associated
  626.         memory.
  627.  
  628.     INPUTS
  629.         picture    - pointer to a picture to be deleted.
  630.         
  631.     SEE ALSO
  632.         MakePictureA()
  633.  
  634.  
  635. guigfx.library/DirectDrawTrueColorA       guigfx.library/DirectDrawTrueColorA
  636.  
  637.     NAME
  638.         DirectDrawTrueColorA - draw truecolor data. (v9)
  639.         DirectDrawTrueColor - varargs stub for DirectDrawTrueColorA.
  640.  
  641.     SYNOPSIS
  642.         success = DirectDrawTrueColorA(directdrawhandle,array,x, y,
  643.         d0                             a0               a1    d0 d1
  644.                                        taglist)
  645.                                        a2
  646.  
  647.         BOOL DirectDrawTrueColorA(APTR,ULONG *,UWORD,UWORD,
  648.                                   struct TagItem *)
  649.  
  650.         BOOL DirectDrawTrueColor(APTR,ULONG *,UWORD,UWORD,Tag,...,
  651.                                  TAG_DONE)
  652.  
  653.     FUNCTION
  654.         Draw an array of truecolor data of the type PIXFMT_0RGB_32 to the
  655.         RastPort associated with a direct-drawhandle's parent drawhandle.
  656.         This function has got very few overhead and writes (or renders)
  657.         the data as straightforward as possible.
  658.  
  659.     INPUTS
  660.         directdrawhandle - an object derived from a drawhandle via
  661.                            CreateDirectDrawHandleA()
  662.         array            - pointer to an array of data of the type
  663.                            PIXFMT_0RGB_32
  664.         x,y              - destination coordinates inside the RastPort.
  665.         taglist          - pointer to an array of TagItems.
  666.         
  667.     TAGS
  668.         GGFX_SourceWidth - total width of source array [pixels]
  669.                            default: sourcewidth supplied with
  670.                            CreateDirectDrawHandleA()
  671.  
  672.     RESULTS
  673.         success          - TRUE if the call succeeded. failures are
  674.                            currently very unlikely, but you should be
  675.                            prepared. future implementations might
  676.                            differ and be more likely to fail due to
  677.                            a lack of memory.
  678.  
  679.     SEE ALSO
  680.         CreateDirectDrawHandleA(), DrawPictureA()
  681.  
  682.  
  683. guigfx.library/DoPictureMethodA               guigfx.library/DoPictureMethodA
  684.  
  685.     NAME
  686.         DoPictureMethodA - apply a method to a picture.
  687.         DoPictureMethod  - varargs stub for DoPictureMethodA.
  688.  
  689.     SYNOPSIS
  690.         result = DoPictureMethodA(picture,method,arguments)
  691.                                   a0      d0     a1
  692.  
  693.         ULONG DoPictureMethodA(APTR,ULONG,ULONG *)
  694.         
  695.         ULONG DoPictureMethod(APTR,ULONG,argument,...)
  696.  
  697.     FUNCTION
  698.         This function applies a method to a picture. Arguments and
  699.         results depend on the specified method.
  700.  
  701.     INPUTS
  702.         picture    - pointer to a picture
  703.         method     - method identifier (see below)
  704.         arguments  - pointer to a list of arguments (see below)
  705.  
  706.     METHODS
  707.  
  708.         PICMTHD_AUTOCROP    tags
  709.  
  710.                 crop the picture at its outmost borders with
  711.                 differing pixels. optionally limit the search
  712.                 for differing pixels to an area inside the picture.
  713.  
  714.                 TAGS
  715.                         GGFX_SourceX (ULONG)
  716.                                 left edge of the area to check [pixels]
  717.                                 Default: 0
  718.  
  719.                         GGFX_SourceY (ULONG)
  720.                                 top edge of the area to check [rows]
  721.                                 Default: 0
  722.  
  723.                         GGFX_SourceWidth (ULONG)
  724.                                 width of the area to check [pixels]
  725.                                 Default: the picture's width.
  726.  
  727.                         GGFX_SourceHeight (ULONG)
  728.                                 height of the area to check [rows]
  729.                                 Default: the picture's height.
  730.  
  731.                 RESULTS
  732.                         success (boolean)
  733.  
  734.  
  735.         PICMTHD_CREATEALPHAMASK        rgb, tags
  736.  
  737.                 this method creates an alpha-channel for the given picture.
  738.                 The alpha-channel will be the difference for each pixel in
  739.                 the picture against the specified 0x00rrggbb value.
  740.                 Optionally, a clip area inside the source picture may be
  741.                 specified.
  742.                 
  743.                 TAGS
  744.                         GGFX_SourceX (ULONG)
  745.                                 source left edge in the second picture
  746.                                 [pixels]. Default: 0
  747.  
  748.                         GGFX_SourceY (ULONG)
  749.                                 source top edge in the picture [rows].
  750.                                 Default: 0
  751.  
  752.                         GGFX_SourceWidth (ULONG)
  753.                                 width of an area in the picture [pixels].
  754.                                 Default: the picture's width.
  755.  
  756.                         GGFX_SourceHeight (ULONG)
  757.                                 height of an area in the picture [rows].
  758.                                 Default: the picture's height.
  759.  
  760.                 RESULTS
  761.                         success (boolean)
  762.  
  763.                 NOTES
  764.                         this method requires conversion to PIXFMT_0RGB_32
  765.                         (see annotations below)
  766.  
  767.                 SEE ALSO
  768.                         PICMTHD_SETALPHA
  769.  
  770.  
  771.         PICMTHD_CROP    x, y, width, height, tags
  772.         
  773.                 crop a picture to a rectangle defined throughout
  774.                 position (x|y) and dimensions (width|height)
  775.  
  776.                 TAGS
  777.                         none defined
  778.  
  779.                 RESULTS
  780.                         success (boolean)
  781.  
  782.  
  783.         PICMTHD_FLIPX    tags
  784.  
  785.                 flip image (or a part of it) horizontally.
  786.  
  787.                 TAGS
  788.                         GGFX_DestX (ULONG)
  789.                                 left edge of the area to flip [pixels]
  790.                                 Default: 0
  791.  
  792.                         GGFX_DestY (ULONG)
  793.                                 top edge of the area to flip [rows]
  794.                                 Default: 0
  795.  
  796.                         GGFX_DestWidth (ULONG)
  797.                                 width of the area to be flipped [pixels]
  798.                                 Default: the picture's width.
  799.  
  800.                         GGFX_DestHeight (ULONG)
  801.                                 height of the area to be flipped [rows]
  802.                                 Default: the picture's height.
  803.  
  804.                 RESULTS
  805.                         success (boolean)
  806.  
  807.  
  808.         PICMTHD_FLIPY    tags
  809.  
  810.                 flip image (or a part of it) vertically.
  811.  
  812.                 TAGS
  813.                         GGFX_DestX (ULONG)
  814.                                 left edge of the area to flip [pixels]
  815.                                 Default: 0
  816.  
  817.                         GGFX_DestY (ULONG)
  818.                                 top edge of the area to flip [rows]
  819.                                 Default: 0
  820.  
  821.                         GGFX_DestWidth (ULONG)
  822.                                 width of the area to be flipped [pixels]
  823.                                 Default: the picture's width.
  824.  
  825.                         GGFX_DestHeight (ULONG)
  826.                                 height of the area to be flipped [rows]
  827.                                 Default: the picture's height.
  828.  
  829.                 RESULTS
  830.                         success (boolean)
  831.  
  832.  
  833.         PICMTHD_INSERT  second_picture, tags
  834.         
  835.                 insert a second picture (or a part of it) to the current
  836.                 picture. Clip areas may be specified both inside the current
  837.                 and the second picture. The processed pixels will be scaled
  838.                 to the specified dimensions, if necessary.
  839.                 
  840.                 TAGS
  841.                         GGFX_SourceX (ULONG)
  842.                                 source left edge where to fetch the pixels
  843.                                 from in the second picture [pixels].
  844.                                 Default: 0
  845.  
  846.                         GGFX_SourceY (ULONG)
  847.                                 source top edge where to fetch the pixels
  848.                                 from in the second picture [rows].
  849.                                 Default: 0
  850.  
  851.                         GGFX_SourceWidth (ULONG)
  852.                                 width of an area in the second picture
  853.                                 [pixels]. Default: the second picture's
  854.                                 width.
  855.  
  856.                         GGFX_SourceHeight (ULONG)
  857.                                 height of an area in the second picture
  858.                                 [rows]. Default: the second picture's
  859.                                 height.
  860.  
  861.                         GGFX_DestX (ULONG)
  862.                                 destination left edge where to insert
  863.                                 the pixels into the current picture
  864.                                 [pixels]. Default: 0
  865.  
  866.                         GGFX_DestY (ULONG)
  867.                                 destination top edge where to insert
  868.                                 the pixels into the current picture
  869.                                 [rows]. Default: 0
  870.  
  871.                         GGFX_DestWidth (ULONG)
  872.                                 width to be inserted in the current picture.
  873.                                 [pixels]. Default: the current picture's width.
  874.  
  875.                         GGFX_DestHeight (ULONG)
  876.                                 height to be inserted in the current picture.
  877.                                 [rows]. Default: the current picture's height.
  878.                                 
  879.                 RESULTS
  880.                         success (boolean)
  881.  
  882.                 NOTES
  883.                         this method requires conversion to PIXFMT_0RGB_32
  884.                         (see annotations below)
  885.  
  886.  
  887.         PICMTHD_MAPDRAWHANDLE   drawhandle, tags
  888.  
  889.                 map a picture for optimized drawing to a drawhandle's
  890.                 RastPort. Drawing a picture via DrawPictureA() is much
  891.                 faster thereafter.
  892.  
  893.                 TAGS
  894.                         none defined
  895.  
  896.                 RESULTS
  897.                         success (boolean)
  898.  
  899.                 NOTES
  900.                         - The internal representation of a picture may
  901.                           change at any time. The specified pixel format
  902.                           is only valid until the next call to
  903.                           DoPictureMethodA(). Use GetPictureAttrsA() to
  904.                           find out about the current format.
  905.  
  906.                         - You risk to lose color information, i.e. when
  907.                           a truecolor picture has to be rendered to a
  908.                           8bit RastPort, for instance.
  909.  
  910.         PICMTHD_MIX     second_picture, tags
  911.         
  912.                 mix a second picture to the current picture. Clip areas
  913.                 may be specified both inside the current and the second
  914.                 picture. The processed pixels will be scaled to the
  915.                 specified dimensions, if necessary.
  916.                 
  917.                 TAGS
  918.                         GGFX_Ratio (ULONG)
  919.                                 mix ratio (0...255). Default: 128
  920.  
  921.                         GGFX_SourceX (ULONG)
  922.                                 source left edge where to fetch pixels
  923.                                 from in the second picture [pixels].
  924.                                 Default: 0
  925.  
  926.                         GGFX_SourceY (ULONG)
  927.                                 source top edge where to fetch pixels
  928.                                 from in the second picture [rows].
  929.                                 Default: 0
  930.  
  931.                         GGFX_SourceWidth (ULONG)
  932.                                 width of an area in the second picture
  933.                                 [pixels]. Default: the second picture's
  934.                                 width.
  935.  
  936.                         GGFX_SourceHeight (ULONG)
  937.                                 height of an area in the second picture
  938.                                 [rows]. Default: the second picture's
  939.                                 height.
  940.  
  941.                         GGFX_DestX (ULONG)
  942.                                 destination left edge where to apply
  943.                                 the operation to in the current picture
  944.                                 [pixels]. Default: 0
  945.  
  946.                         GGFX_DestY (ULONG)
  947.                                 destination top edge where to apply
  948.                                 the operation to in the current picture
  949.                                 [rows]. Default: 0
  950.  
  951.                         GGFX_DestWidth (ULONG)
  952.                                 width of an area for the operation to be
  953.                                 applied to in the current picture [pixels].
  954.                                 Default: the current picture's width.
  955.  
  956.                         GGFX_DestHeight (ULONG)
  957.                                 height of an area for the operation to be
  958.                                 applied to in the current picture [rows].
  959.                                 Default: the current picture's height.
  960.                                 
  961.                 RESULTS
  962.                         success (boolean)
  963.  
  964.                 NOTES
  965.                         this method requires conversion to PIXFMT_0RGB_32
  966.                         (see annotations below)
  967.  
  968.                 SEE ALSO
  969.                         PICMTHD_MIXALPHA
  970.  
  971.  
  972.         PICMTHD_MIXALPHA        secondpicture, tags
  973.         
  974.                 mix a second picture to the current picture via
  975.                 alpha-channel. Clip areas may be specified both inside
  976.                 the current and the second picture. The processed pixels
  977.                 will be scaled to the specified dimensions, if necessary.
  978.                 
  979.                 TAGS
  980.                         GGFX_SourceX (ULONG)
  981.                                 source left edge where to fetch pixels
  982.                                 from in the second picture [pixels].
  983.                                 Default: 0
  984.  
  985.                         GGFX_SourceY (ULONG)
  986.                                 source top edge where to fetch pixels
  987.                                 from in the second picture [rows].
  988.                                 Default: 0
  989.  
  990.                         GGFX_SourceWidth (ULONG)
  991.                                 width of an area in the second picture
  992.                                 [pixels]. Default: the second picture's
  993.                                 width.
  994.  
  995.                         GGFX_SourceHeight (ULONG)
  996.                                 height of an area in the second picture
  997.                                 [rows]. Default: the second picture's
  998.                                 height.
  999.  
  1000.                         GGFX_DestX (ULONG)
  1001.                                 destination left edge where to apply
  1002.                                 the operation to in the current picture
  1003.                                 [pixels]. Default: 0
  1004.  
  1005.                         GGFX_DestY (ULONG)
  1006.                                 destination left edge where to apply
  1007.                                 the operation to in the current picture
  1008.                                 [rows]. Default: 0
  1009.  
  1010.                         GGFX_DestWidth (ULONG)
  1011.                                 width of an area for the operation to be
  1012.                                 applied to in the current picture [pixels].
  1013.                                 Default: the current picture's width.
  1014.  
  1015.                         GGFX_DestHeight (ULONG)
  1016.                                 height of an area for the operation to be
  1017.                                 applied to in the current picture [rows].
  1018.                                 Default: the current picture's height.
  1019.                                 
  1020.                 RESULTS
  1021.                         success (boolean)
  1022.  
  1023.                 NOTES
  1024.                         this method requires conversion to PIXFMT_0RGB_32
  1025.                         (see annotations below)
  1026.  
  1027.                 SEE ALSO
  1028.                         PICMTHD_SETALPHA, PICMTHD_MIX
  1029.  
  1030.  
  1031.         PICMTHD_NEGATIVE    tags
  1032.  
  1033.                 invert the colors of the picture (or a part of it)
  1034.  
  1035.                 TAGS
  1036.                         GGFX_DestX (ULONG)
  1037.                                 left edge of the area to invert [pixels]
  1038.                                 Default: 0
  1039.  
  1040.                         GGFX_DestY (ULONG)
  1041.                                 top edge of the area to invert [rows]
  1042.                                 Default: 0
  1043.  
  1044.                         GGFX_DestWidth (ULONG)
  1045.                                 width of the area to invert [pixels]
  1046.                                 Default: the picture's width.
  1047.  
  1048.                         GGFX_DestHeight (ULONG)
  1049.                                 height of the area to invert [rows]
  1050.                                 Default: the picture's height.
  1051.  
  1052.                 RESULTS
  1053.                         success (boolean)
  1054.  
  1055.                 NOTES
  1056.                         this method requires conversion to PIXFMT_0RGB_32
  1057.                         (see annotations below)
  1058.  
  1059.  
  1060.         PICMTHD_RENDER  pixelformat, tags
  1061.  
  1062.                 render a picture to a specified pixel format. Valid pixel
  1063.                 formats are as follows:
  1064.  
  1065.                         PIXFMT_CHUNKY_CLUT
  1066.                                 chunky bytes
  1067.                         
  1068.                         PIXFMT_0RGB_32
  1069.                                 ULONG 0x00rrggbb truecolor data
  1070.  
  1071.                         PIXFMT_RGB_24
  1072.                                 UBYTE 0xrr,0xgg,0xbb truecolor data
  1073.                 
  1074.                 TAGS
  1075.                         none defined
  1076.                         
  1077.                 RESULTS
  1078.                         success (boolean)
  1079.  
  1080.                 NOTES
  1081.                         - The internal representation of a picture may
  1082.                           change at any time. The specified pixel format
  1083.                           is only valid until the next call to
  1084.                           DoPictureMethodA(). Use GetPictureAttrsA() to
  1085.                           find out about the current format.
  1086.  
  1087.                         - You risk to lose color information, i.e. when
  1088.                           a truecolor picture is rendered to
  1089.                           PIXFMT_CHUNKY_CLUT.
  1090.  
  1091.  
  1092.         PICMTHD_SCALE   width, height, tags
  1093.         
  1094.                 scale a picture to the specified dimensions.
  1095.                 
  1096.                 TAGS
  1097.                         none defined
  1098.  
  1099.                 RESULTS
  1100.                         success (boolean)
  1101.                         
  1102.                 NOTE
  1103.                         This function fails if applied to a static
  1104.                         buffer, and when the image needs to grow. In this
  1105.                         case, specify GGFX_Independent or set a larger
  1106.                         buffer with GGFX_BufferSize when creating the
  1107.                         picture with MakePictureA().
  1108.  
  1109.  
  1110.         PICMTHD_SET     rgb, tags
  1111.         
  1112.                 set a picture (or a part of it) to the specified
  1113.                 RGB value.
  1114.  
  1115.                 TAGS
  1116.                         GGFX_DestX (ULONG)
  1117.                                 destination left edge [pixels]
  1118.                                 Default: 0
  1119.  
  1120.                         GGFX_DestY (ULONG)
  1121.                                 destination top edge [rows]
  1122.                                 Default: 0
  1123.  
  1124.                         GGFX_DestWidth (ULONG)
  1125.                                 width to be affected [pixels]
  1126.                                 Default: the picture's width.
  1127.  
  1128.                         GGFX_DestHeight (ULONG)
  1129.                                 height to be affected [rows]
  1130.                                 Default: the picture's height.
  1131.  
  1132.                 RESULTS
  1133.                         success (boolean)
  1134.                 
  1135.                 NOTES
  1136.                         if you apply this method to a picture of the
  1137.                         format PIXFMT_CHUNKY_CLUT, it cannot be
  1138.                         guaranteed that the specified RGB value
  1139.                         is exactly hit. you can use PICMTHD_RENDER
  1140.                         in order to convert the picture to
  1141.                         PIXFMT_0RGB_32 before. 
  1142.  
  1143.  
  1144.         PICMTHD_SETALPHA        alpha-array, width, height, tags
  1145.  
  1146.                 set an alpha-channel array for the current picture.
  1147.                 The alpha-channel is a plain array of chunky-bytes,
  1148.                 defining a mixing ratio for each pixel. The
  1149.                 alpha-channel array will be scaled to fit exactly to
  1150.                 the current picture, unless you specify other
  1151.                 dimensions. Passing a NULL pointer for alpha-array
  1152.                 will discard an existing alpha-channel.
  1153.  
  1154.                 TAGS
  1155.                         GGFX_DestX (ULONG)
  1156.                                 destination left edge where to insert
  1157.                                 the alpha-channel into the current
  1158.                                 picture [pixels]. Default: 0
  1159.  
  1160.                         GGFX_DestY (ULONG)
  1161.                                 destination top edge where to insert
  1162.                                 the alpha-channel into the current
  1163.                                 picture [rows]. Default: 0
  1164.  
  1165.                         GGFX_DestWidth (ULONG)
  1166.                                 width to be inserted to the current
  1167.                                 picture [pixels]. Default: the current
  1168.                                 picture's width.
  1169.  
  1170.                         GGFX_DestHeight (ULONG)
  1171.                                 height to be inserted to the current
  1172.                                 picture [rows]. Default: the current
  1173.                                 picture's height.
  1174.  
  1175.                 RESULTS
  1176.                         success (boolean)
  1177.                 
  1178.                 NOTES
  1179.                         this method requires conversion to PIXFMT_0RGB_32
  1180.                         (see annotations below)
  1181.  
  1182.                 SEE ALSO
  1183.                         PICMTHD_CREATEALPHAMASK
  1184.  
  1185.  
  1186.         PICMTHD_TEXTURE  texturepic, coordinates, tags
  1187.         
  1188.                 draw a texture to the current picture, texture-mapped
  1189.                 via an array of coordinates. texturepic is a pointer to
  1190.                 a picture that contains the texture, coordinates is a
  1191.                 pointer to an array of 4 WORD pairs of x/y coordinates
  1192.                 each. They form a trapezoid inside the current picture
  1193.                 for the texture picture to be mapped to. border clipping
  1194.                 is fully implemented.
  1195.  
  1196.                 TAGS
  1197.                         GGFX_SourceX (ULONG)
  1198.                                 source left edge inside the texture
  1199.                                 [pixels]. Default: 0
  1200.  
  1201.                         GGFX_SourceY (ULONG)
  1202.                                 source top edge inside the texture
  1203.                                 [rows]. Default: 0
  1204.  
  1205.                         GGFX_SourceWidth (ULONG)
  1206.                                 texture width [pixels]. Default:
  1207.                                 the texturepic's width.
  1208.  
  1209.                         GGFX_SourceHeight (ULONG)
  1210.                                 texture height [rows]. Default:
  1211.                                 the texturepic's height.
  1212.  
  1213.                         GGFX_DestX (ULONG)
  1214.                                 destination left edge where to apply
  1215.                                 the trapezoid to the current picture
  1216.                                 [pixels]. Default: 0
  1217.  
  1218.                         GGFX_DestY (ULONG)
  1219.                                 destination top edge where to apply
  1220.                                 the trapezoid to the current picture
  1221.                                 [rows]. Default: 0
  1222.  
  1223.                         GGFX_DestWidth (ULONG)
  1224.                                 maximum width to be inserted to the
  1225.                                 current picture [pixels]. Default: the
  1226.                                 current picture's width.
  1227.  
  1228.                         GGFX_DestHeight (ULONG)
  1229.                                 maximum height to be inserted to the
  1230.                                 current picture [rows]. Default: the
  1231.                                 current picture's height.
  1232.                         
  1233.                 RESULTS
  1234.                         success (boolean)
  1235.  
  1236.                 NOTES
  1237.                         this method depends on both pictures to be in
  1238.                         the same format. DoPictureMethodA() tries to
  1239.                         convert either of the involved pictures to the
  1240.                         other's format. (see annotations below)
  1241.  
  1242.                 SEE ALSO
  1243.                         render.library texture-mapping documentation
  1244.  
  1245.  
  1246.         PICMTHD_TINTALPHA       rgb, tags
  1247.         
  1248.                 tint the picture with the given 0x00rrggbb. the mixing
  1249.                 ratio is defined throughout the picture's alpha-channel.
  1250.                 
  1251.                 TAGS
  1252.                         GGFX_DestX (ULONG)
  1253.                                 destination left edge where to apply
  1254.                                 the operation [pixels]. Default: 0
  1255.  
  1256.                         GGFX_DestY (ULONG)
  1257.                                 destination left edge where to apply
  1258.                                 the operation [rows]. Default: 0
  1259.  
  1260.                         GGFX_DestWidth (ULONG)
  1261.                                 width of an area for the operation to be
  1262.                                 applied to [pixels].
  1263.                                 Default: the picture's width.
  1264.  
  1265.                         GGFX_DestHeight (ULONG)
  1266.                                 height of an area for the operation to be
  1267.                                 applied to [rows].
  1268.                                 Default: the picture's height.
  1269.  
  1270.                 RESULTS
  1271.                         success (boolean)
  1272.  
  1273.                 NOTES
  1274.                         this method requires conversion to PIXFMT_0RGB_32
  1275.                         (see annotations below)
  1276.  
  1277.                 SEE ALSO
  1278.                         PICMTHD_TINT, PICMTHD_MIXALPHA
  1279.  
  1280.  
  1281.         PICMTHD_TINT     rgb, tags
  1282.         
  1283.                 tint the picture with the given 0x00rrggbb value, and
  1284.                 optionally with a specific ratio.
  1285.                 
  1286.                 TAGS
  1287.                         GGFX_Ratio (ULONG)
  1288.                                 mix ratio (0...255). Default: 128
  1289.  
  1290.                         GGFX_DestX (ULONG)
  1291.                                 destination left edge where to apply
  1292.                                 the operation [pixels]. Default: 0
  1293.  
  1294.                         GGFX_DestY (ULONG)
  1295.                                 destination left edge where to apply
  1296.                                 the operation [rows]. Default: 0
  1297.  
  1298.                         GGFX_DestWidth (ULONG)
  1299.                                 width of an area for the operation to be
  1300.                                 applied to [pixels].
  1301.                                 Default: the picture's width.
  1302.  
  1303.                         GGFX_DestHeight (ULONG)
  1304.                                 height of an area for the operation to be
  1305.                                 applied to [rows].
  1306.                                 Default: the picture's height.
  1307.  
  1308.                 RESULTS
  1309.                         success (boolean)
  1310.  
  1311.                 NOTES
  1312.                         this method requires conversion to PIXFMT_0RGB_32
  1313.                         (see annotations below)
  1314.  
  1315.                 SEE ALSO
  1316.                         PICMTHD_TINTALPHA, PICMTHD_MIXALPHA
  1317.  
  1318.  
  1319.     RESULTS
  1320.         result     - return value (specific for the applied method)
  1321.  
  1322.     NOTES
  1323.         Methods that require conversion to PIXFMT_0RGB_32 will fail in
  1324.         a static buffer, i.e. when the picture was created with
  1325.         MakePictureA() in the format PIXFMT_CHUNKY_CLUT, and without
  1326.         a buffer overhang or GGFX_Independent. See MakePictureA() for
  1327.         further details.
  1328.         
  1329.     SEE ALSO
  1330.         MakePictureA(), ObtainDrawHandleA(), DrawPictureA()
  1331.  
  1332.  
  1333. guigfx.library/DrawPictureA                       guigfx.library/DrawPictureA
  1334.  
  1335.     NAME
  1336.         DrawPictureA - draw a picture to a drawhandle.
  1337.         DrawPicture  - varargs stub for DrawPictureA.
  1338.  
  1339.     SYNOPSIS
  1340.         success = DrawPictureA(drawhandle,picture,x, y, tags)
  1341.         d0                     a0         a1      d0 d1 a2
  1342.  
  1343.         BOOL DrawPictureA(APTR,APTR,UWORD,UWORD,struct TagItem *)
  1344.  
  1345.         BOOL DrawPicture(APTR,APTR,UWORD,UWORD,tag,...,TAG_DONE)
  1346.  
  1347.     FUNCTION
  1348.         This function draws a picture to the RastPort associated with
  1349.         a drawhandle. Optionally, the picture will be scaled to the
  1350.         specified dimensions. A clip area inside the picture may be
  1351.         specified as well.
  1352.  
  1353.     INPUTS
  1354.         drawhandle  - pointer to a drawhandle from ObtainDrawHandleA()
  1355.         picture     - pointer to a picture
  1356.         x           - left edge inside the RastPort [pixels]
  1357.         y           - top edge inside the RastPort [rows]
  1358.         tags        - pointer to an array of TagItems
  1359.  
  1360.     TAGS
  1361.         GGFX_SourceX (ULONG)
  1362.                 left edge inside the picture where to fetch the pixels
  1363.                 from [pixels]. Default: 0.
  1364.  
  1365.         GGFX_SourceY (ULONG)
  1366.                 top edge inside the picture where to fetch the pixels
  1367.                 from [rows]. Default: 0.
  1368.  
  1369.         GGFX_SourceWidth (ULONG)
  1370.                 width of an area inside the picture [pixels].
  1371.                 Default: The picture's width.
  1372.  
  1373.         GGFX_SourceHeight (ULONG)
  1374.                 height of an area inside the picture [rows].
  1375.                 Default: The picture's height.
  1376.  
  1377.         GGFX_DestWidth (ULONG)
  1378.                 destination width for the picture to be drawn [pixels].
  1379.                 Default: the picture's width.
  1380.  
  1381.         GGFX_DestHeight (ULONG)
  1382.                 destination height for the picture to be drawn [rows].
  1383.                 Default: the picture's height.
  1384.  
  1385.         GGFX_CallBackHook (struct Hook *)
  1386.                 pointer to a callback Hook structure. The associated
  1387.                 callback function will be called from time to time
  1388.                 while the picture is being drawn.
  1389.                 The callback has to return TRUE for continuation or FALSE
  1390.                 for abortion. It will be submitted a pointer to the
  1391.                 picture for the object, and a message of the following
  1392.                 type:
  1393.  
  1394.                         ULONG GGFX_MSGTYPE_LINEDRAWN
  1395.                         ULONG line_number
  1396.                 
  1397.                 Also refer to the example below.
  1398.                 Default: NULL.
  1399.  
  1400.         GGFX_DitherMode (ULONG) - dither mode. Currently available are:
  1401.  
  1402.                 DITHERMODE_NONE
  1403.                         no dithering at all
  1404.                 
  1405.                 DITHERMODE_FS
  1406.                         Floyd-Steinberg dithering
  1407.                         
  1408.                 DITHERMODE_RANDOM
  1409.                         Random dithering. This mode is significantly
  1410.                         slower than Floyd-Steinberg dithering.
  1411.  
  1412.                 DITHERMODE_EDD
  1413.                         EDD dithering. This mode is faster than
  1414.                         Floyd-Steinberg dithering.
  1415.                         
  1416.                 Default: The drawhandle's dithermode.
  1417.  
  1418.         GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
  1419.                 Currently, this value is of any use only for
  1420.                 DITHERMODE_RANDOM. Default: The drawhandle's dither amount.
  1421.  
  1422.         GGFX_AutoDither (BOOL) - automatic dither activation.
  1423.                 If set to TRUE, dithering is automatically activated for
  1424.                 drawing a particular picture to a particular environment,
  1425.                 when the loss of color information would exceed a certain
  1426.                 threshold (see below). Default: TRUE
  1427.         
  1428.         GGFX_RastLock (struct SignalSemaphore *) - pointer to an
  1429.                 initialized exec.library SignalSemaphore which is
  1430.                 used for RastPort sharing between tasks. if you want
  1431.                 to draw to the drawhandle's RastPort while another
  1432.                 task is rendering to this RastPort with DrawPictureA(),
  1433.                 you must supply this argument and enclose all accesses
  1434.                 to the RastPort with ObtainSemaphore()/ReleaseSemaphore()
  1435.                 pairs. default: NULL (v16)
  1436.  
  1437.     RESULTS
  1438.         success     - TRUE if the picture could be drawn, FALSE
  1439.                       if there was not enough memory available.
  1440.                       Another reason for this function to fail is that
  1441.                       the optional callback hook returned FALSE.
  1442.  
  1443.     NOTES
  1444.         There is almost no overhead for scaling. Scaling is extremely
  1445.         fast and may be considered 'gratis'.
  1446.  
  1447.     EXAMPLE
  1448.         The callback hook allows to interrupt DrawPictureA() at any time. A
  1449.         simple callback function might look like this:
  1450.  
  1451.         ULONG __saveds __asm abortdrawfunc(register __a0 struct Hook *hook)
  1452.         {
  1453.             ULONG abortsignal = 1 << *((BYTE *) (hook->h_Data));
  1454.             if (SetSignal(0, 0) & abortsignal)
  1455.             {
  1456.                 return FALSE;
  1457.             }
  1458.             else
  1459.             {
  1460.                 return TRUE;
  1461.             }
  1462.         }
  1463.         
  1464.         In this example, an abortion signal was allocated and made available
  1465.         to the function via h_Data. If the signal arrives, the callback
  1466.         function returns FALSE to DrawPictureA(), and drawing will be
  1467.         interrupted.
  1468.         
  1469.         Note: Not all internal drawing-routines actually execute the hook
  1470.         function more than once. This mainly depends on the typical speed
  1471.         for a particular drawing routine or certain graphics.library or
  1472.         cybergraphics.library implementations. At least it is supported
  1473.         when scaling and rendering is involved to the drawing process.
  1474.  
  1475.     SEE ALSO
  1476.         ObtainDrawHandleA(), CreatePictureBitMapA()
  1477.  
  1478.  
  1479. guigfx.library/GetPictureAttrsA               guigfx.library/GetPictureAttrsA
  1480.  
  1481.     NAME
  1482.         GetPictureAttrsA - get picture attributes.
  1483.         GetPictureAttrs  - varargs stub for GetPictureAttrsA.
  1484.  
  1485.     SYNOPSIS
  1486.         count = GetPictureAttrsA(picture,tags)
  1487.         d0                       a0      a1
  1488.  
  1489.         ULONG GetPictureAttrsA(APTR,struct TagItem *)
  1490.  
  1491.         ULONG GetPictureAttrs(APTR,tag,...,TAG_DONE)
  1492.  
  1493.     FUNCTION
  1494.         This function obtains a list of picture attributes. It
  1495.         returns the number of attributes that have been retrieved
  1496.         actually.
  1497.  
  1498.     INPUTS
  1499.         picture     - pointer to a picture
  1500.         tags        - pointer to an array of TagItems
  1501.  
  1502.     TAGS
  1503.         PICATTR_Width (ULONG *)
  1504.                 The picture's width [pixels]
  1505.  
  1506.         PICATTR_Height (ULONG *)
  1507.                 The picture's height [rows]
  1508.  
  1509.         PICATTR_PixelFormat (ULONG *)
  1510.                 The picture's internal pixel format. Currently this
  1511.                 can be PIXFMT_CHUNKY_CLUT, PIXFMT_0RGB_32, or
  1512.                 PIXFMT_RGB_24.
  1513.  
  1514.         PICATTR_RawData (APTR *)
  1515.                 Pointer to the picture's raw data. Operate on the raw
  1516.                 pixel array only with knowledge of the actual pixel
  1517.                 format. Warning: The internal representation of a picture
  1518.                 may change with every call to DoPictureMethodA() or
  1519.                 drawing functions.
  1520.  
  1521.         PICATTR_AspectX (ULONG *)
  1522.                 Horizontal pixel aspect.
  1523.  
  1524.         PICATTR_AspectY (ULONG *)
  1525.                 Vertical pixel aspect.
  1526.  
  1527.         PICATTR_AlphaPresent (BOOL)
  1528.                 indicates if an alpha-channel is present.
  1529.  
  1530.     RESULTS
  1531.         count  - the number of attributes that could be retrieved.
  1532.  
  1533.  
  1534. guigfx.library/IsPictureA                           guigfx.library/IsPictureA
  1535.  
  1536.     NAME
  1537.         IsPictureA - determine whether a file is a picture or not. (v4)
  1538.         IsPicture  - varargs stub for IsPictureA.
  1539.  
  1540.     SYNOPSIS
  1541.         ispicture = IsPictureA(filename,tags)
  1542.         d0                     a0       a1
  1543.  
  1544.         BOOL IsPictureA(char *,struct TagItem *)
  1545.  
  1546.         BOOL IsPicture(char *,tag,...,TAG_DONE)
  1547.  
  1548.     FUNCTION
  1549.         This function checks if the specified file could be loaded
  1550.         as a picture with LoadPictureA().
  1551.  
  1552.     INPUTS
  1553.         filename    - name of the file to be checked
  1554.         tags        - pointer to an array of TagItems
  1555.  
  1556.     TAGS
  1557.  
  1558.     RESULTS
  1559.         ispicture   - TRUE if the specified file is recognized
  1560.                       as a picture that could be loaded with
  1561.                       LoadPictureA().
  1562.  
  1563.     SEE ALSO
  1564.         LoadPictureA()
  1565.  
  1566.  
  1567. guigfx.library/LoadPictureA                       guigfx.library/LoadPictureA
  1568.  
  1569.     NAME
  1570.         LoadPictureA - load a picture file.
  1571.         LoadPicture  - varargs stub for LoadPictureA.
  1572.  
  1573.     SYNOPSIS
  1574.         picture = LoadPictureA(filename,tags)
  1575.         d0                     a0       a1
  1576.  
  1577.         APTR LoadPictureA(char *,struct TagItem *)
  1578.  
  1579.         APTR LoadPicture(char *,tag,...,TAG_DONE)
  1580.  
  1581.     FUNCTION
  1582.         This function loads a picture. Currently, this is implemented
  1583.         via picture.class datatypes.
  1584.  
  1585.     INPUTS
  1586.         filename    - name of the file to be loaded
  1587.         tags        - pointer to an array of TagItems
  1588.  
  1589.     TAGS
  1590.         GGFX_ErrorCode (LONG *)
  1591.                 Pointer to a variable that will receive a standard DOS
  1592.                 error code. This will be NULL if loading was successful.
  1593.                 Default: NULL
  1594.         
  1595.         GGFX_UseMask (ULONG) (v15)
  1596.                 boolean to indicate whether a transparency color,
  1597.                 an alpha-channel or a mask (if present) should be
  1598.                 inserted to the picture. Note: This tag requires the
  1599.                 picture to be converted to PIXFMT_0RGB_32.
  1600.                 Default: FALSE              
  1601.  
  1602.         GGFX_HSType (ULONG) - picture's internal histogram type, according
  1603.                 to the histogram types defined in render/render.h.
  1604.                 Better you never touch this tag, unless you know exactly
  1605.                 what you are doing. Consider reading the 'memory' text
  1606.                 file supplied with the render.library distribution.
  1607.                 You do not need this tag under normal circumstances.
  1608.                 Default: not defined (will be set to the pen-sharemap's
  1609.                 histogram type, or to the default type when needed)
  1610.  
  1611.     RESULTS
  1612.         picture  - pointer to a picture or NULL if something went wrong.
  1613.                    The exact reason for failure can be obtained via the
  1614.                    GGFX_ErrorCode tag.
  1615.  
  1616.     NOTES
  1617.         - As for current datatype implementations, alpha-channels
  1618.         do not seem to be supported. The datatype might translate
  1619.         it to a single bitplane.
  1620.         guigfx.library, on the other hand, does not (yet) support
  1621.         single-bitplane masks, so masks and transparency colors will
  1622.         be translated to alpha-channels.
  1623.                    
  1624.     SEE ALSO
  1625.         DeletePicture(), IsPictureA(), MakePictureA(), ReadPictureA()
  1626.  
  1627.  
  1628. guigfx.library/LockPictureA                       guigfx.library/LockPictureA
  1629.  
  1630.     NAME
  1631.         LockPictureA - lock picture attributes. (v3)
  1632.         LockPicture  - varargs stub for LockPictureA.
  1633.         
  1634.         *** obsolete ***
  1635.  
  1636.     SYNOPSIS
  1637.         success = LockPictureA(picture,flags,arguments)
  1638.         d0                     a0      d0    a1
  1639.  
  1640.         BOOL LockPictureA(APTR,ULONG,ULONG *)
  1641.         
  1642.         BOOL LockPicture(APTR,ULONG,argument,...)
  1643.  
  1644.     FUNCTION
  1645.         This function locks certain picture attributes and
  1646.         prevents the picture from internal conversions that
  1647.         affect the specified flags.
  1648.  
  1649.     INPUTS
  1650.         picture     - pointer to a picture
  1651.         flags       - locking flags
  1652.         arguments   - flag-specific arguments
  1653.  
  1654.     FLAGS
  1655.         LOCKMODE_DRAWHANDLE drawhandle
  1656.         
  1657.                 lock the picture to the specified drawhandle.
  1658.                 this leads to optimized drawing without the
  1659.                 need to render. combine with LOCKMODE_FORCE
  1660.                 if you want to lock the image even if color
  1661.                 information would be lost.
  1662.  
  1663.     RESULTS
  1664.         success  - TRUE if locking was successful, FALSE if
  1665.                    locking is not possible, or if locking
  1666.                    required a conversion with loss of
  1667.                    color information.
  1668.  
  1669.     NOTES
  1670.         This function is currently (v4) not working, and it
  1671.         will always return FALSE. If you need optimized drawing,
  1672.         use the method PICMTHD_MAPDRAWHANDLE instead.
  1673.  
  1674.     SEE ALSO
  1675.         UnLockPicture(), DoPictureMethodA()
  1676.  
  1677.  
  1678. guigfx.library/MakePictureA                       guigfx.library/MakePictureA
  1679.  
  1680.     NAME
  1681.         MakePictureA - make a picture from raw data or from a BitMap.
  1682.         MakePicture  - varargs stub for MakePictureA.
  1683.  
  1684.     SYNOPSIS
  1685.         picture = MakePictureA(data,width,height,tags)
  1686.         d0                     a0   d0    d1     a1
  1687.  
  1688.         APTR MakePictureA(APTR,UWORD,UWORD,struct TagItem *)
  1689.  
  1690.         APTR MakePicture(APTR,UWORD,UWORD,tag,...,TAG_DONE)
  1691.  
  1692.     FUNCTION
  1693.         This function makes a picture from an array of raw
  1694.         data (or a part of it), or from a BitMap structure
  1695.         (or a part of it). Optionally, memory is allocated
  1696.         for a 'blank' picture. Optionally, the picture will
  1697.         be scaled.
  1698.  
  1699.         Raw data is not incorporated to the picture, instead
  1700.         it is referenced at its original location in memory,
  1701.         unless you specify the tag GGFX_Independent. (This does
  1702.         not apply to BitMap structures - pictures created from
  1703.         BitMaps are always independent.)
  1704.  
  1705.         If GGFX_Independent is not specified (and your picture
  1706.         is taken from its original location in memory), you may
  1707.         additionally specify a buffer 'overhang' with the tag
  1708.         GGFX_BufferSize. This allows internal conversions which
  1709.         require the image to grow at its original location in
  1710.         memory. You must be the owner of that memory, of course.
  1711.  
  1712.     INPUTS
  1713.         data    - pointer to
  1714.                   - an array of truecolor data,
  1715.                   - an array of chunky pixels,
  1716.                   - a BitMap structure
  1717.                   or NULL.
  1718.         width   - total width of the source array or BitMap [pixels]
  1719.         height  - total height of the source array or BitMap [rows]
  1720.         tags    - pointer to an array of TagItems
  1721.  
  1722.     TAGS
  1723.         GGFX_PixelFormat (ULONG) - pixel format. Currently defined are
  1724.  
  1725.                 PIXFMT_CHUNKY_CLUT
  1726.                         chunky bytes, directly acting as indices
  1727.                         to a color-lookup-table.
  1728.                 
  1729.                 PIXFMT_0RGB_32
  1730.                         truecolor pixels (ULONG 0xaarrggbb).
  1731.  
  1732.                 PIXFMT_BITMAP_CLUT
  1733.                         a BitMap structure with normal palette lookup.
  1734.                         You must also specify the GGFX_Palette and
  1735.                         GGFX_NumColors tags.
  1736.  
  1737.                 PIXFMT_BITMAP_HAM8
  1738.                         a BitMap structure with HAM8 color lookup.
  1739.                         You must also specify the GGFX_Palette and
  1740.                         GGFX_NumColors tags.
  1741.  
  1742.                 PIXFMT_BITMAP_HAM6
  1743.                         a BitMap structure with HAM6 color lookup.
  1744.                         You must also specify the GGFX_Palette and
  1745.                         GGFX_NumColors tags.
  1746.  
  1747.                 PIXFMT_BITMAP_RGB
  1748.                         a BitMap structure which is assumed to contain
  1749.                         truecolor data. This may apply to CyberGraphX
  1750.                         bitmaps.
  1751.  
  1752.                 Default: PIXFMT_CHUNKY_CLUT               
  1753.  
  1754.  
  1755.         GGFX_Palette (APTR) - pointer to a color table. If this
  1756.                 tag is not specified with PIXFMT_CHUNKY_CLUT, a
  1757.                 default palette of 256 grey tones will be generated.
  1758.                 Default: NULL
  1759.  
  1760.         GGFX_NumColors (ULONG) - number of colors in the color table.
  1761.                 This tag is mandatory when GGFX_Palette is specified
  1762.                 (see above). Default: not defined
  1763.                 
  1764.         GGFX_PaletteFormat (ULONG) - format of the palette. Currently
  1765.                 defined are:
  1766.                       
  1767.                 PALFMT_RGB8
  1768.                         ULONG 0x00rrggbb
  1769.  
  1770.                 PALFMT_RGB32
  1771.                         ULONG red,green,blue. This is the LoadRGB32()
  1772.                         format without trailing longword.
  1773.  
  1774.                 Default: PALFMT_RGB8
  1775.  
  1776.         GGFX_SourceX (ULONG) - left edge of an area inside the array
  1777.                 or BitMap [pixels]. Default: 0.
  1778.  
  1779.         GGFX_SourceY (ULONG) - top edge of an area inside the array
  1780.                 or BitMap [rows]. Default: 0.
  1781.  
  1782.         GGFX_SourceWidth (ULONG) - width of an area inside the array
  1783.                 or BitMap [pixels]. Default: width.
  1784.         
  1785.         GGFX_SourceHeight (ULONG) - height of an area inside the array
  1786.                 or BitMap [rows]. Default: height.
  1787.  
  1788.         GGFX_DestWidth (ULONG) - destination width of the resulting
  1789.                 picture [pixels]. Default: GGFX_SourceWidth.
  1790.         
  1791.         GGFX_DestHeight (ULONG) - destination height for the resulting
  1792.                 picture [rows]. Default: GGFX_SourceHeight.
  1793.  
  1794.         GGFX_BufferSize (ULONG) - total size of the specified buffer
  1795.                 in bytes. This defines an 'oversized' buffer for the
  1796.                 array of pixels. It informs the picture to what size
  1797.                 it may grow for internal conversions.
  1798.                 This tag is ignored when you supply a BitMap structure,
  1799.                 or when GGFX_Independent is specified.
  1800.                 Default: Required size in bytes
  1801.                 for width * height * bytes_per_pixel.
  1802.  
  1803.         GGFX_AspectX (ULONG) - picture's horizontal aspect.
  1804.                 Default: 1
  1805.  
  1806.         GGFX_AspectY (ULONG) - picture's vertical aspect.
  1807.                 Default: 1
  1808.  
  1809.         GGFX_AlphaPresent (BOOL) - flag to indicate that the array
  1810.                 contains alpha-channel information. This tag is only
  1811.                 considered with PIXFMT_0RGB_32. Default: FALSE
  1812.  
  1813.         GGFX_Independent (BOOL) - If set to TRUE, the pixel array will
  1814.                 always be copied to a seperate buffer that is maintained
  1815.                 with the picture internally. This tag is meaningless when
  1816.                 the input data is a BitMap structure. Default: FALSE
  1817.  
  1818.         GGFX_HSType (ULONG) - picture's internal histogram type, according
  1819.                 to the histogram types defined in render/render.h.
  1820.                 Better you never touch this tag, unless you know exactly
  1821.                 what you are doing. Consider reading the 'memory' text
  1822.                 file supplied with the render.library distribution.
  1823.                 You do not need this tag under normal circumstances.
  1824.                 Default: not defined (will be set to a pensharemap's
  1825.                 histogram type, or to the default type when needed)
  1826.  
  1827.     RESULTS
  1828.         picture  - pointer to a picture or NULL if something went wrong.
  1829.  
  1830.     SEE ALSO
  1831.         DeletePicture(), LoadPictureA(), ReadPictureA()
  1832.  
  1833.  
  1834. guigfx.library/ObtainDrawHandleA             guigfx.library/ObtainDrawHandleA
  1835.  
  1836.     NAME
  1837.         ObtainDrawHandleA - obtain a handle for drawing.
  1838.         ObtainDrawHandle  - varargs stub for ObtainDrawHandleA.
  1839.  
  1840.     SYNOPSIS
  1841.         drawhandle = ObtainDrawHandleA(pensharemap,rastport,colormap,tags)
  1842.         d0                             a0          a1       a2       a3
  1843.  
  1844.         APTR ObtainDrawHandleA(APTR,struct RastPort *,struct ColorMap *,
  1845.                                struct TagItem *)
  1846.  
  1847.         APTR ObtainDrawHandle(APTR,struct RastPort *,struct ColorMap *,
  1848.                               tag,...,TAG_DONE)
  1849.  
  1850.     FUNCTION
  1851.         This function obtains a drawhandle for drawing to a RastPort.
  1852.         Depending on the RastPort's environment, pens may be allocated
  1853.         from the ColorMap.
  1854.  
  1855.         Before a pen-sharemap is passed to this function, it has to
  1856.         be loaded with colors via AddPictureA(), AddPaletteA(), and/or
  1857.         AddPixelArrayA(). Otherwise ObtainDrawHandleA() returns NULL.
  1858.         
  1859.         Optionally, you may specify NULL for the pen-sharemap argument,
  1860.         in which case a drawhandle for a static palette will be
  1861.         generated.
  1862.  
  1863.     INPUTS
  1864.         pensharemap - pointer to a pen-sharemap created with
  1865.                       CreatePenShareMapA(), or NULL.
  1866.         rastport    - pointer to a RastPort
  1867.         colormap    - pointer to a ColorMap. Usually, this is
  1868.                       screen->ViewPort.ColorMap of the rastport's screen.
  1869.         tags        - pointer to an array of TagItems
  1870.  
  1871.     TAGS
  1872.         OBP_Precision (ULONG) - precision for pen allocations,
  1873.                 according to the definitions in graphics/view.h.
  1874.                 See also graphics.library/ObtainBestPenA().
  1875.                 Default: PRECISION_IMAGE.
  1876.                 
  1877.                 Note: The default precision suffices for almost every
  1878.                 application. ObtainDrawHandleA() obtains pens in an
  1879.                 extremely effective way. You get excellent results
  1880.                 even with lower precisions. Commodore's idea with
  1881.                 ObtainBestPenA() was to create a fair and effective
  1882.                 pen-sharing mechanism, and ObtainDrawHandleA() behaves
  1883.                 in perfect accordance to this intention. Never use
  1884.                 insane patches for ObtainBestPenA().
  1885.                 
  1886.         GGFX_DitherMode (ULONG) - dither mode. Currently available are:
  1887.  
  1888.                 DITHERMODE_NONE
  1889.                         no dithering at all
  1890.                 
  1891.                 DITHERMODE_FS
  1892.                         Floyd-Steinberg dithering
  1893.                         
  1894.                 DITHERMODE_RANDOM
  1895.                         Random dithering. This mode is significantly
  1896.                         slower than Floyd-Steinberg dithering.
  1897.  
  1898.                 DITHERMODE_EDD
  1899.                         EDD dithering. This mode is faster than
  1900.                         Floyd-Steinberg dithering.
  1901.                 
  1902.                 Default: DITHERMODE_FS.
  1903.  
  1904.         GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
  1905.                 Currently this value is of any use only for
  1906.                 DITHERMODE_RANDOM. Default: 40
  1907.  
  1908.         GGFX_AutoDither (BOOL) - automatic dither activation.
  1909.                 If set to TRUE, dithering is automatically activated for
  1910.                 drawing a particular picture to a particular environment,
  1911.                 when the loss of color information would exceed a certain
  1912.                 threshold (see below). Default: TRUE
  1913.  
  1914.         GGFX_DitherThreshold (ULONG) - threshold for automatic dithering.
  1915.                 The lower, the earlier automatic dithering is activated.
  1916.                 Useful thresholds range between 10 and 10000. Refer to
  1917.                 render.library/RGBArrayDiversityA() for further details.
  1918.                 better you do not use this tag unless you have a good
  1919.                 reason to. let the user customize it with the environment
  1920.                 variable AUTODITHERTHRESHOLD. Default: 250
  1921.  
  1922.         GGFX_MaxAllocPens (ULONG) - limit for the number of pens to be
  1923.                 allocated from the ColorMap. Do not use this feature
  1924.                 unless you have a good reason to. Valid range: 0...256.
  1925.                 Default: not defined
  1926.  
  1927.         GGFX_ModeID (ULONG) - screen's modeID. Currently, this is required
  1928.                 for guigfx.library to detect HAM modes. The full HAM
  1929.                 color range can be achieved only with this tag specified.
  1930.                 Default: INVALID_ID (no HAM detection takes place)
  1931.  
  1932.     RESULTS
  1933.         drawhandle - pointer to a handle for drawing to rastports.
  1934.                      NULL if something went wrong.
  1935.  
  1936.     SEE ALSO
  1937.         ReleaseDrawHandle(), CreatePenShareMapA(), DrawPictureA(),
  1938.         graphics.library/ObtainBestPenA(),
  1939.         render.library/RGBArrayDiversityA()
  1940.  
  1941.  
  1942. guigfx.library/ReadPictureA                       guigfx.library/ReadPictureA
  1943.  
  1944.     NAME
  1945.         ReadPictureA - read a picture from a RastPort.
  1946.         ReadPicture  - varargs stub for ReadPictureA.
  1947.  
  1948.     SYNOPSIS
  1949.         picture = ReadPictureA(rastport,colormap,x, y, width,height,tags)
  1950.         d0                     a0       a1       d0 d1 d2    d3     a2
  1951.  
  1952.         APTR ReadPictureA(struct RastPort *,struct ColorMap *,UWORD,UWORD,
  1953.                           UWORD,UWORD,struct TagItem *)
  1954.  
  1955.         APTR ReadPicture(struct RastPort *,struct ColorMap *,UWORD,UWORD,
  1956.                          UWORD,UWORD,tag,...,TAG_DONE)
  1957.  
  1958.     FUNCTION
  1959.         This function reads a picture from a RastPort (or a part of it),
  1960.         and optionally scales it to the specified dimensions.
  1961.  
  1962.     INPUTS
  1963.         rastport - pointer to a RastPort where to fetch the pixels from
  1964.         colormap - pointer to a ColorMap where to fetch color information
  1965.                    from. Usually this is screen->ViewPort.ColorMap of the
  1966.                    specified RastPort's Screen.
  1967.         x        - left edge in the RastPort [pixels]
  1968.         y        - top edge in the RastPort [rows]
  1969.         width    - width of the area to be read [pixels]
  1970.         height   - height of the area to be read [rows]
  1971.         tags     - pointer to an array of TagItems
  1972.  
  1973.     TAGS
  1974.         GGFX_DestWidth (ULONG) - destination width [pixels].
  1975.                 Default: width.
  1976.         
  1977.         GGFX_DestHeight (ULONG) - destination height [rows].
  1978.                 Default: height.
  1979.         
  1980.         GGFX_AspectX (ULONG) - horizontal pixel aspect for the resulting
  1981.               picture. Default: 1
  1982.  
  1983.         GGFX_AspectY (ULONG) - vertical pixel aspect for the resulting
  1984.               picture. Default: 1
  1985.  
  1986.         GGFX_ModeID (ULONG) - screen's mode ID. currently required for
  1987.               determining HAM rastports. Default: none
  1988.        
  1989.         GGFX_HSType (ULONG) - picture's internal histogram type, according
  1990.                 to the histogram types defined in render/render.h.
  1991.                 Better you never touch this tag, unless you know exactly
  1992.                 what you are doing. Consider reading the 'memory' text
  1993.                 file supplied with the render.library documentation.
  1994.  
  1995.     RESULTS
  1996.         picture  - pointer to a picture or NULL if not enough memory.
  1997.  
  1998.     SEE ALSO
  1999.         LoadPictureA(), MakePictureA()
  2000.  
  2001.  
  2002. guigfx.library/ReleaseDrawHandle             guigfx.library/ReleaseDrawHandle
  2003.  
  2004.     NAME
  2005.         ReleaseDrawHandle - free a drawhandle.
  2006.  
  2007.     SYNOPSIS
  2008.         ReleaseDrawHandle(drawhandle)
  2009.                           a0
  2010.  
  2011.         void ReleaseDrawHandle(APTR)
  2012.  
  2013.     FUNCTION
  2014.         This function discards a drawhandle, frees associated memory, and
  2015.         returns allocated pens (if any) to the related ColorMap.
  2016.  
  2017.     INPUTS
  2018.         drawhandle    - drawhandle obtained via ObtainDrawHandleA()
  2019.         
  2020.     SEE ALSO
  2021.         ObtainDrawHandleA()
  2022.  
  2023.  
  2024. guigfx.library/RemColorHandle                   guigfx.library/RemColorHandle
  2025.  
  2026.     NAME
  2027.         RemColorHandle - manually remove a colorhandle.
  2028.  
  2029.     SYNOPSIS
  2030.         RemColorHandle(colorhandle)
  2031.                        a0
  2032.  
  2033.         void RemColorHandle(APTR)
  2034.  
  2035.     FUNCTION
  2036.         This function removes particular color information from
  2037.         a pen-sharemap. Further calls to ObtainDrawHandleA() may
  2038.         lead to different pen allocations then.
  2039.  
  2040.     INPUTS
  2041.         colorhandle    - pointer to a colorhandle from
  2042.                          AddPictureA(), AddPaletteA(),
  2043.                          or AddPixelArrayA()
  2044.  
  2045.     NOTE
  2046.         DeletePenShareMap() arbitrarily frees all its
  2047.         colorhandles. There is no need to manually remove
  2048.         them. This function is only required if you wish to
  2049.         modify a pen-sharemap and then call ObtainDrawHandleA()
  2050.         again.
  2051.         
  2052.         Calling RemColorHandle() for colorhandles that have
  2053.         been removed with DeletePenShareMap() will be fatal.
  2054.  
  2055.     SEE ALSO
  2056.         AddPictureA(), AddPaletteA(), AddPixelArrayA(),
  2057.         DeletePenShareMap(), ObtainDrawHandleA()
  2058.  
  2059.  
  2060. guigfx.library/UnLockPicture                     guigfx.library/UnLockPicture
  2061.  
  2062.     NAME
  2063.         UnLockPicture - unlock picture attributes (v3)
  2064.  
  2065.         *** obsolete ***
  2066.  
  2067.     SYNOPSIS
  2068.         UnLockPicture(picture,flags)
  2069.                       a0      d0
  2070.  
  2071.         UnLockPicture(APTR,ULONG)
  2072.  
  2073.     FUNCTION
  2074.         This function frees picture attributes that have been
  2075.         locked with LockPictureA().
  2076.  
  2077.     INPUTS
  2078.         picture     - pointer to a picture
  2079.         flags       - flags to unlock
  2080.  
  2081.     RESULTS
  2082.         none
  2083.  
  2084.     SEE ALSO
  2085.         LockPictureA()
  2086.  
  2087.     NOTES
  2088.         This function will currently (v4) do nothing. Read
  2089.         the annotations in LockPictureA().
  2090.